/*
 * utils.h
 * 串口调试工具 - 工具功能模块头文件
 * 
 * 此文件包含通用工具函数的声明，包括数据统计、字符串处理、时间戳管理等功能。
 */

#ifndef UTILS_H
#define UTILS_H

#include <QString>
#include <QByteArray>
#include <QDateTime>
#include <QStringList>

/**
 * @brief 工具函数命名空间
 */
namespace Utils {

/**
 * @brief 格式化字节大小显示
 * @param bytes 字节数
 * @return 格式化后的字符串
 */
QString formatByteSize(quint64 bytes);

/**
 * @brief 生成当前时间戳
 * @param format 时间格式字符串
 * @return 时间戳字符串
 */
QString generateTimestamp(const QString &format = "yyyy-MM-dd HH:mm:ss.zzz");

/**
 * @brief 计算两个时间点之间的毫秒差
 * @param startTime 开始时间
 * @param endTime 结束时间
 * @return 时间差（毫秒）
 */
double calculateTimeDifference(const QDateTime &startTime, const QDateTime &endTime);

/**
 * @brief 计算数据传输速率
 * @param bytes 字节数
 * @param milliseconds 毫秒数
 * @return 速率（字节/秒）
 */
double calculateTransferRate(quint64 bytes, double milliseconds);

/**
 * @brief 十六进制字符串转字节数组
 * @param hexString 十六进制字符串
 * @return 字节数组
 */
QByteArray hexStringToByteArray(const QString &hexString);

/**
 * @brief 字节数组转十六进制字符串
 * @param byteArray 字节数组
 * @param separator 分隔符
 * @return 十六进制字符串
 */
QString byteArrayToHexString(const QByteArray &byteArray, const QString &separator = " ");

/**
 * @brief 验证十六进制字符串
 * @param hexString 要验证的字符串
 * @return 是否为有效的十六进制字符串
 */
bool isValidHexString(const QString &hexString);

/**
 * @brief 在文本中查找内容并高亮
 * @param text 原始文本
 * @param searchText 要查找的文本
 * @param caseSensitive 是否区分大小写
 * @return 高亮后的HTML文本
 */
QString highlightSearchText(const QString &text, const QString &searchText, bool caseSensitive = false);

/**
 * @brief 限制文本行数
 * @param text 原始文本
 * @param maxLines 最大行数
 * @return 限制后的文本
 */
QString limitTextLines(const QString &text, int maxLines);

/**
 * @brief 确保字符串使用系统换行符
 * @param text 原始文本
 * @return 使用系统换行符的文本
 */
QString normalizeNewlines(const QString &text);

/**
 * @brief 安全地解析整数
 * @param text 文本字符串
 * @param defaultValue 默认值
 * @return 解析结果
 */
int safeParseInt(const QString &text, int defaultValue = 0);

/**
 * @brief 生成唯一标识符
 * @return 唯一标识符字符串
 */
QString generateUniqueId();

/**
 * @brief 检查文件是否可写
 * @param filePath 文件路径
 * @return 是否可写
 */
bool isFileWritable(const QString &filePath);

/**
 * @brief 创建目录（如果不存在）
 * @param dirPath 目录路径
 * @return 是否创建成功
 */
bool ensureDirectoryExists(const QString &dirPath);

/**
 * @brief 获取文件扩展名
 * @param filePath 文件路径
 * @return 扩展名（不包含点）
 */
QString getFileExtension(const QString &filePath);

/**
 * @brief 获取不带扩展名的文件名
 * @param filePath 文件路径
 * @return 文件名（不带扩展名）
 */
QString getFileNameWithoutExtension(const QString &filePath);

/**
 * @brief 格式化持续时间
 * @param milliseconds 毫秒数
 * @return 格式化的时间字符串
 */
QString formatDuration(quint64 milliseconds);

/**
 * @brief 解析波特率字符串
 * @param baudRateStr 波特率字符串
 * @return 波特率数值，如果无效返回0
 */
int parseBaudRate(const QString &baudRateStr);

/**
 * @brief 验证文件路径是否有效
 * @param filePath 文件路径
 * @return 是否有效
 */
bool isValidFilePath(const QString &filePath);

/**
 * @brief 清理文件名中的无效字符
 * @param fileName 文件名
 * @return 清理后的文件名
 */
QString sanitizeFileName(const QString &fileName);

/**
 * @brief 读取文件内容
 * @param filePath 文件路径
 * @param error 错误信息输出
 * @return 文件内容
 */
QString readFileContent(const QString &filePath, QString &error);

/**
 * @brief 写入文件内容
 * @param filePath 文件路径
 * @param content 内容
 * @param error 错误信息输出
 * @return 是否成功
 */
bool writeFileContent(const QString &filePath, const QString &content, QString &error);

/**
 * @brief 计算字符串的校验和
 * @param str 字符串
 * @return 校验和值
 */
char calculateChecksum(const QString &str);

/**
 * @brief 格式化十六进制转储
 * @param data 数据
 * @param width 每行宽度
 * @return 格式化的十六进制转储字符串
 */
QString formatHexDump(const QByteArray &data, int width = 16);

/**
 * @brief 生成随机数据
 * @param size 数据大小
 * @return 随机数据
 */
QByteArray generateRandomData(int size);

/**
 * @brief 将字符串分割成块
 * @param str 字符串
 * @param chunkSize 块大小
 * @return 字符串块列表
 */
QStringList splitStringIntoChunks(const QString &str, int chunkSize);

/**
 * @brief 用分隔符连接字符串
 * @param strings 字符串列表
 * @param separator 分隔符
 * @return 连接后的字符串
 */
QString joinStringsWithSeparator(const QStringList &strings, const QString &separator);

/**
 * @brief 从字符串中提取数字
 * @param text 文本
 * @return 提取的数字列表
 */
QStringList extractNumbers(const QString &text);

/**
 * @brief 验证IP地址是否有效
 * @param ipAddress IP地址
 * @return 是否有效
 */
bool isValidIpAddress(const QString &ipAddress);

/**
 * @brief 验证端口号是否有效
 * @param port 端口号
 * @return 是否有效
 */
bool isValidPortNumber(int port);

/**
 * @brief 将整数转换为二进制字符串
 * @param value 整数值
 * @param bits 位数
 * @return 二进制字符串
 */
QString intToBinaryString(int value, int bits = 8);

/**
 * @brief 解析版本字符串
 * @param version 版本字符串
 * @return 版本号组件列表
 */
QList<int> parseVersionString(const QString &version);

/**
 * @brief 比较版本字符串
 * @param version1 版本1
 * @param version2 版本2
 * @return -1: version1 < version2, 0: version1 == version2, 1: version1 > version2
 */
int compareVersionStrings(const QString &version1, const QString &version2);

}

#endif // UTILS_H